AEMail 2.40

home *** CD-ROM | disk | FTP | other *** search

/ AEMail 2.40 / AEMail v2.40.iso / arexx / aemail-arexx.doc < prev next >

Wrap

Text File | 2000-03-11 | 73KB | 1,866 lines

AEMAIL AREXX INTERFACE Introduction ------------ AEMail has a very powerful set of ARexx commands that can be used to control AEMail from external ARexx scripts. You can also execute ARexx scripts and AmigaDOS scripts from within AEMail. When you want to send commands from an ARexx script to AEMail, you must tell ARexx how to locate the AEMail ARexx message port. The AEMail ARexx Port Name is normally "AEMAIL1". You can change this port name with the use of the "AREXXPORT=" tool type (See TOOL TYPES under Section IV. CONFIGURATION). The current Arexx Port Name is shown in the About message obtained with the "About" item under the Project Menu. You tell ARexx what the message port name for AEMail is by using the ARexx ADDRESS commmand in an ARexx script like this: ADDRESS AEMAIL1 If you call an ARexx script from AEMail, the ADDRESS command is automatically set to the AEMail ARexx message port. There are several ways you can execute an ARexx script in AEMail. You can use the ARexx/DOS menu items "Send AREXX/DOS Command...", "Send Last Command", or, if a menu title has been assigned to the ARexx script, by the menu item with that title (see VII. AEMAIL MENUS). You can also bind ARexx scripts to a function key. You can have up to 40 selections since the Shift, CTRL, and ALT keys can be used in conjunction with the function keys. When you press the appropriate function key the ARexx script bonded to it will be executed. Two event exits have also been provided which can have ARexx scripts executed when you double click on a web address or an email address in a message. Setting the menu title, the event exits, or the function key assigned to the command is done with the ARexx Page of the Configuration Setup (See Section IV. Configuration). After each command directed at AEMail from an ARexx script is executed, the standard ARexx result variable, RC, will report the success or failure of the command. A 0 in RC indicates that the command was understood and executed successfully. An RC value other than 0 indicates an error severity indicator. The exact error text is reported in the Arexx AEMAIL.LASTERROR variable. All of the AEMail ARexx commands also report back information if they were executed successfully (RC = 0). This information is reported in the ARexx variable RESULT. To receive this information you must supply the following ARexx command at the beginning of the ARexx script: OPTIONS RESULTS You will notice that some commands have possible negative numbers for RESULT values. The RESULT variable usually returns either a numeric value or a string. If a numeric value is returned and if it is positive and above zero, the expected result was achieved. If the value was 0 or negative, the expected result was not achieved. Some commands that normally return strings in the RESULT variable may also return a NULL string or a negative numeric value. The negative numeric value is used to denote various reasons the string value was not returned. If there is only one reason, the command will normally return a "0" or a NULL value; but if there is more than one reason, the additional reasons will be indicated with a negative number. An example would be a command that is expected to return the Subject: from the current message. A result of NULL or blank indicates that there was no Subject: header and a result of "-1" indicates that there is no current message. These two conditions need to be distinguished. Below is a both a list of the currently available AEMail ARexx commands and a section which describes each command in detail. Many of the commands are available to registered users only. These will be so noted in the command list. Some of the commands are composed of multiple words. To avoid confusion these multiple words are sometimes separated by an underline character ("_"). As an example "ADDRESS_BOOK" separates ADDRESS and BOOK with the underline. This is to avoid confusion with "ADDRESS" which is a standard ARexx command. If an underline is required, it will be shown in the command syntax. QUOTING: Some command have parameters with embedded ARexx command characters such as +, -, |, etc. To avoid the possibilty of ARexx interpreting these as ARexx operations, the parameter should be surrounded by quotes (either single or double quotes). An example of where this is very important is the first parameter of the OKAY2 command. Each of the possible responses in the OKAY2 command is separated by a vertical bar ("|") such as "OK|CANCEL". The entire response parameter needs to be surrounded in quotes as shown or otherwise the vertical bar will be intrepreted by ARexx as an "inclusive or" operation. Another condition requiring quoting is passing strings with embedded spaces. This usually requires a bit of "creative" quoting because ARexx always strips at least one set of quotation marks from all strings. Fortunately ARexx considers both the double quote (") and the single quote (') as quotes. To provide for the proper treatment of strings with embedded spaces (such as some file and path names or title strings), you have to use a double grouping of quotes. For example: GETFILENAME '"The Title String"' '"A file name path"' will send "The Title String" and "A file name path" to AEMail which will recognize these strings as two quoted operands. ARexx variables which might have embedded spaces in their contents must also be quoted as above. You can do this as follows: filename = "A file name path" title = "The Title String" GETFILENAME '"'title'"' '"'filename'"' This ensures that ARexx, when it strips off a set of quotation marks and replaces the variables with their contents, will also pass a set of quotation marks around the resulting strings. AEMail will then recognize the passed strings as two string operands rather than many unconnected words. Synopsis of ARexx Commands -------------------------- The following is a list of the currently available AEMail ARexx commands. This list also indicates which commands are only available to registered users with an (R) following the command. A complete description of all of the commands and the command variations follows this list. ADDRESS_BOOK (R) Manipulates the AEMail Address Book BCC (R) Returns the BCC header in a message CC (R) Returns the CC header in a message COMPOSE Composes a message CURRENT IS SELECTED Makes the selected message current DATE (R) Returns the DATE header in a message EXTRACT (R) Parses a name string to real name or email address FIRST (R) Selects first message in folder or name in name string FLAGS (R) Returns the flags in a message FOLDER (R) Returns information on folders FROM (R) Returns the FROM header in a message GETCLIP (R) Get a clip from the clipboard GETFILENAME Brings up the AEMail file requester GETLISTITEM Brings up the AEMail list view requester GETNUMBER Brings up the AEMail numeric requester GETSIZE (R) Returns the size of a message or message body GETSTRING Brings up the AEMail string requester GETVAR Gets a variable from message LAST (R) Selects last message in a folder MESSAGE (R) Sets various flags in a message NEXT (R) Selects next message in folder or name in name string OKAY1 Brings up AEMail notification requester OKAY2 Brings up AEMail notification requester with responses PREVIOUS (R) Selects the previous message in a folder QUEUE Queues a passed message QUIT Terminates AEMail REPLYTO (R) Returns the REPLY-TO header in a message SAVE (R) Saves a message or message text SCREENTOBACK Brings a screen to the back of the display SCREENTOFRONT Brings a screen to the front of the display SUBJECT (R) Returns the SUBJECT header in a message TO (R) Returns the TO header in a message ARexx Commands -------------- The following is a description of all of the currently available AEMail ARexx commands in alphabetical order. Shown with each of the commands is what you can expect to have returned in the RESULT variable. Please note the use of the OKAY1 and OKAY2 commands. You can use these to report back information to the AEMail user. These commands put up a requester with the information you provide. You will also notice in the command descriptions the use of the term "current message". This applies to ARexx commands only and is not the "selected message" that is indicated by an asterick (*) in the displayed message list; although, you can make the most recent (current) "selected message" the "current message" (see the CURRENT IS SELECTED command below) and you can "select" a current message (the MESSAGE SELECT command). Initially "current message" is un-defined, but once it is defined it will remain defined through multiple calls from ARexx scripts until AEMail terminates or the "current message" is changed through the use of another ARexx command. ADDRESS_BOOK This command is used to manipulate the AEMail Address Book. There are a number of variations of the ADDRESS_BOOK command. They are listed below. If the correct command keyword ("LIST", "FIND", "ADD", etc.) is not present, an RC code of severity level 5 will be returned and AEMAIL.LASTERROR will contain "101: Syntax Error". Note the use of the parameter called "userid". This can be either an email address or a referenced nickname pointing to another individual or group entry. When a userid is returned, you can test if it is a nickname by using the ADDRESS_BOOK GET nickname TYPE command. *** Syntax: ADDRESS_BOOK LIST ALL [DESCRIPTION] [pad] ADDRESS_BOOK LIST GROUP [DESCRIPTION] [pad] ADDRESS_BOOK LIST INDIVIDUAL [DESCRIPTION] [pad] This command will list the nicknames in your address book. The operand "ALL" will list all of the nicknames, the operand "GROUP" will list just the group nicknames, and "INDIVIDUAL" will list just the individual nicknames. The optional keyword "DESCRIPTION" can be used to also return the Description or Real Name field following the nickname. In this event the nickname will be padded out with spaces so that so that it will be a fixed length of 11 characters (always ending with at least one space). This means that the description field will always start in a fixed position. Normally each nickname is separated by a space. However, this can be changed by a specifying a pad string at the end of the command. You can use the LF keyword to specify a line feed or use some other character sequence for the pad string. As an example: ", " will insert a comma followed by a space between each nickname in the list. RESULT: The list of nicknames separated by the pad character. *** Syntax: ADDRESS_BOOK FIND nickname [userid] This command is used to find out if a particular userid (email address or referenced nickname) is contained in a group entry in the Address Book. You can explicity give the userid or the email address can be obtained from the current message. If the userid is not specified, both the From: and Reply-To: addresses from the current message will be used to check if the email address is in the group entry specified by nickname. The nickname operand is required and must be a group nickname. RESULT: -3 No current message if userid not given -2 The nickname is not for a group entry in the Address Book -1 The nickname given is not in the Address Book. 0 The userid was not found 1 The userid found. If not supplied, the userid that was found was an email address from the From: address in the current message. 2 The Reply-To: address in the current message was found in the group. 3 Both the Reply-To: and From: addresses were found. Note: these addresses may actually be the same. *** Syntax: ADDRESS_BOOK CREATE GROUP nickname ["SEND-HEADER-ONLY"|SHO], FROM|REPLYTO|userid description This entry creates a new group entry in the Address Book. When you create a group entry you must have one userid (email address or referenced nickname) entry to place in the group. You are not allowed to have a group without any entries. The nickname for the new group must be supplied and it must not be greater than 9 characters. It can not, of course, match any existing nickname. "SEND-HEADER-ONLY" is an optional keyword operand which sets the "Send Header Only" flag in the group entry and must be quoted. You can use the shorthand abreviation "SHO" instead of the full "SEND-HEADER-ONLY" string. The userid which is added can be explicity specified or it can be the email address taken from either the From: or Reply-To: address in the current message. Use the keyword operands "FROM" or "REPLYTO" to specify which header field in the current message is to be used. If you specify "REPLYTO" and that header is missing, an error condition will be returned (see below). There is no validation performed on the user_id. If it is an email address it should be one word without any intervening spaces. It should be within a quoted string to avoid confusion with ARexx special symbols. If it is a nickname with embedded spaces it must be double quoted (two pairs of quote marks - ie, '"........"'. The description operand is placed in the "Real Name" field in the Address Book entry and must be given. It may have embedded spaces and should be quoted. If you want quotes to appear in the group description you should use the ARexx method for including embedded quotes (i.e., '"....string...."' or '"'variable'"'. RESULT: -4 The REPLYTO operand was specified and there is no Reply-To: header in the current message. -3 No current message if userid not given -1 The nickname given is greater than 9 characters. 0 The nickname given was already defined in the Address Book. 1 The group entry was successfully created. *** Syntax: ADDRESS_BOOK ADD TO GROUP nickname FROM ADDRESS_BOOK ADD TO GROUP nickname REPLYTO ADDRESS_BOOK ADD TO GROUP nickname userid This command adds an userid (email address or referenced nickname) to an existing group in the Address Book. The nickname operand specifies the group the userid is to be added to and is a required parameter. The userid which is added can be explicity specified or it can be the email address taken from either the From: or Reply-To: address in the current message. Use the keyword operands "FROM" or "REPLYTO" to specify which header field in the current message is to be used. If you specify "REPLYTO" and that header is missing, an error condition will be returned (see below). There is no validation performed on the user_id. If it is an email address it should be one word without any intervening spaces. It should be within a quoted string to avoid confusion with ARexx special symbols. If it is a nickname with embedded spaces it must be double quoted (two pairs of quote marks - ie, '"........"'. RESULT: -4 The REPLYTO operand was specified and there is no Reply-To: header in the current message. -3 No current message if userid not specified. -2 The nickname is not for a group entry in the Address Book -1 The nickname given was not found. 0 The userid given was already defined in the group. 1 The userid was successfully added to the group. *** Syntax: ADDRESS_BOOK ADD INDIVIDUAL nickname FROM [real-name] ADDRESS_BOOK ADD INDIVIDUAL nickname REPLYTO [real-name] ADDRESS_BOOK ADD INDIVIDUAL nickname userid [real-name] This command adds a new individual nickname to the Address Book. The nickname for the new group must be supplied and it must not be greater than 9 characters. It can not, of course, match any existing nickname. The userid which is assign to the new nickname is required and can be explicity specified or it can be the email address taken from either the From: or Reply-To: header in the current message. Use the keyword operands "FROM" or "REPLYTO" to specify which header field in the current message is to be used. If you specify "REPLYTO" and that header is missing, an error condition will be returned (see below). There is no validation performed on the user_id. If it is an email address it should be one word without any intervening spaces. It should be within a quoted string to avoid confusion with ARexx special symbols. If it is a nickname with embedded spaces it must be double quoted (two pairs of quote marks - ie, '"........"'. The real-name operand is placed in the "Real Name" field in the Address Book entry. It is an optional entry. It may have intervening spaces. It should be quoted. If you want quotes to appear in the group description you should use the ARexx method for including embedded quotes (i.e., '"....string...."' or '"'variable'"'. If a current message is used to obtain the userid (either the "FROM" or "REPLYTO" keyword operands) any real name supplied with the header will take precedence over the real-name operand if it is present. RESULT: -4 The REPLYTO operand was specified and there is no Reply-To: header in the current message. -3 No current message if userid not specified. -1 The nickname given is greater than 9 characters. 0 The nickname given was already defined. 1 The nickname and userid was successfully added to the Address Book. *** Syntax: ADDRESS_BOOK DELETE FROM GROUP nickname FROM ADDRESS_BOOK DELETE FROM GROUP nickname REPLYTO ADDRESS_BOOK DELETE FROM GROUP nickname userid This command deletes a userid from the group indicated by nickname. The userid which is to be deleted is required and can be explicity specified or it can be the email address taken from either the From: or Reply-To: address in the current message. Use the keyword operands "FROM" or "REPLYTO" to specify which header field in the current message is to be used. If you specify "REPLYTO" and that header is missing, an error condition will be returned (see below). There is no validation performed on the user_id. If it is an email address it should be one word without any intervening spaces. It should be within a quoted string to avoid confusion with ARexx special symbols. If it is a nickname with embedded spaces it must be double quoted (two pairs of quote marks - ie, '"........"'. If the userid is the only userid in the group, it will not be deleted. No group can exist without at lease one userid. In this special case a RESULT code of -5 will be returned. To delete the one remaining userid you must delete the entire group (see "ADDRESS-BOOK DELETE GROUP" below. RESULT: -5 The userid specified was the only userid in the group and WAS NOT DELETED. Use the "ADDRESS_BOOK DELETE GROUP" command to delete entire group. -4 The REPLYTO operand was specified and there is no Reply-To: header in the current message. -3 No current message if userid not specified. -2 The nickname is not for a group entry in the Address Book -1 The nickname given was not found. 0 The userid was not present in the group. 1 The userid was deleted from the group. *** Syntax: ADDRESS_BOOK DELETE GROUP nickname This command deletes the entire group specified by nickname and all of it's associated userids. RESULT: -2 The nickname given is not for a group entry in the Address Book -1 The nickname given was not found. 1 The group was successfully deleted. *** Syntax: ADDRESS_BOOK DELETE INDIVIDUAL nickname This command deletes the nickname provided. It must be the nickname for an individual. RESULT: -2 The nickname given is for a group entry in the Address Book. No deletion was performed. 0 The individual's nickname was not present. 1 The individual's nickname was successfully deleted. *** Syntax: ADDRESS_BOOK GET nickname TYPE This command obtains the type, group or individual, for the Address Book entry specified by "nickname". RESULT: -1 The nickname given does not exist. 0 Nickname was for an individual entry. 1 Nickname was for a group entry. *** Syntax: ADDRESS_BOOK GET nickname REALNAME This command obtains the "Real Name" or Group Description for the Address Book entry specified by "nickname". RESULT: -1 The nickname given does not exist. NULL or blank No real name was present. "Real Name" or group description string *** Syntax: ADDRESS_BOOK GET nickname USERID This command obtains the userid for the Address Book entry specified by "nickname". This command can only be used with Individual nicknames. RESULT: -2 The nickname given is not for an individual entry. -1 The nickname given does not exist. "userid" This may be either an email address or a referenced nickname. Use the ADDRESS_BOOK GET nickname TYPE command to determine if it is a nickname rather than an email address. *** Syntax: ADDRESS_BOOK GET nickname FIRST USERID This command obtains the first userid for the Address Book group entry specified by "nickname". This command can only be used with Group nicknames. This command must be issued before the GET NEXT USERID command described below is issued. When this command is issued it resets the group for which you are attempting to obtain userids. RESULT: -2 The nickname given is not for a group entry. -1 The nickname given does not exist. "userid" This may be either an email address or a referenced nickname. Use the ADDRESS_BOOK GET nickname TYPE command to determine if it is a nickname rather than an email address. *** Syntax: ADDRESS_BOOK GET nickname NEXT USERID This command obtains the next userid for the Address Book group entry specified by "nickname". This command can only be used with Group nicknames. A GET nickname FIRST USERID command must be issued for the same nickname before the a GET nickname NEXT USERID command is issued. This command will continue to get userids for the nickname until a NULL is received which signifies the end of list of userids for the group. If you continue to try to issue NEXT USERID commands after the last userid is obtained you will get an error result as shown below. RESULT: -3 A prior FIRST USERID command was not issued for this group nickname. -2 The nickname given is not for a group entry. -1 The nickname given does not exist OR you have issued the NEXT USERID command after the last one was obtained. "userid" This may be either an email address or a referenced nickname. Use the ADDRESS_BOOK GET nickname TYPE command to determine if it is a nickname rather than an email address. NULL There are no more userids in the group. *** Syntax: ADDRESS_BOOK GET nickname "SEND-HEADER-ONLY-FLAG"|"SHO-FLAG" This command obtains the state of the "Send Header Only" flag for the group entry specified by "nickname". The operand can be specified as either "SEND-HEADER-ONLY-FLAG" or "SHO-FLAG" and must be quoted. This command can only be used with Group nicknames. RESULT: -2 The nickname given was not for a group entry. -1 The nickname given does not exist. 0 The "Send Header Only" Flag was OFF. 1 The "Send Header Only" Flag was ON. *** Syntax: ADDRESS_BOOK GET nickname COUNT This command obtains the count of userid entries in the group entry specified by "nickname". This command is can only be used with Group nicknames. RESULT: -2 The nickname given was not for a group entry. -1 The nickname given does not exist. n The count of userids in the group entry. BCC Syntax: BCC This command returns the bcc: header of the current message without the bcc:. It has no operands. RESULT: -1 No current message NULL or blanks No bcc: header bcc: header CC Syntax: CC This command returns the cc: header of the current message without the cc:. It has no operands. RESULT: -1 No current message NULL or blanks No cc: header cc: header COMPOSE All of the variations of the COMPOSE command bring up the AEMail compose window for further action. If for any reason the Compose window returns any error such as the failure to open the Compose window or an out of memory condition, the error will be returned in AEMAIL.LASTERROR with the RC set to a severity level of 20. This error will not have an error number associated with it. The syntax of the various variations of the COMPOSE command are as follows: *** Syntax: COMPOSE The COMPOSE command without any operands brings up the Compose window to compose a new message. RESULT: 0: User canceled message compose. No message composed. 1: Message composed and placed in PENDING folder. 2: Message composed and placed in QUEUED folder. 3: Message composed and sent. *** Syntax: COMPOSE NEW MESSAGE The Compose window will be brought up to compose a new message. RESULT: 0: User canceled message compose. No message composed. 1: Message composed and placed in PENDING folder. 2: Message composed and placed in QUEUED folder. 3: Message composed and sent. *** Syntax: COMPOSE REPLY The Compose window will be brought up to compose a reply to the current message using the Reply-To: address as the recipient. If the Reply-To: address is not available, the From: address will be used. RESULT: -1: There is no current message defined. 0: The user cancelled the operation. No message was composed. 1: Message composed and placed in PENDING folder. 2: Message composed and placed in QUEUED folder. 3: Message composed and sent. *** Syntax: COMPOSE REPLY FROM The Compose window will be brought up to compose a reply to the current message using the From: address as the recipient. RESULT: -1: There is no current message defined. 0: The user cancelled the operation. No message was composed. 1: Message composed and placed in PENDING folder. 2: Message composed and placed in QUEUED folder. 3: Message composed and sent. *** Syntax: COMPOSE FORWARD [userid] The Compose window will be brought up to forward the current message. If the userid (email address or referenced Address Book nickname) is provided, this will be used as the recipient (To: address) of the forwarded message; otherwise, the To: address will be blank and user will have to provide it. RESULT: -1: There is no current message defined. 0: The user cancelled the operation. No message was composed. 1: Message composed and placed in PENDING folder. 2: Message composed and placed in QUEUED folder. 3: Message composed and sent. *** Syntax: COMPOSE MAILTO userid The Compose window will be brought up to compose a new message to be mailed to the recipient indicated by the userid. The userid can be either an Address Book nickname or a full email-address and must be given. No validation is made on the userid. If it is invalid, either the user will receive an error when the message is sent or a message will be received indicating "Returned mail: User unknown". RESULT: 0: The user cancelled the operation. No message was composed. 1: Message composed and placed in the PENDING folder. 2: Message composed and placed in the QUEUED folder. 3: Message composed and sent. *** Syntax: COMPOSE "message-file-name" The Compose window will be brought up and the message file indicated by "message-file-name" will be read into the system and used as the message to edit. This message must have correctly formatted headers. Only the To:, From:, Reply-To:, Subject:, cc:, and bcc: headers will be recognized. A blank line must separate the headers from the body of the message. The "message-file-name" should be the full path name of the message file and it should be quoted since the path will contain characters that ARexx will attempt to interpret as operators or possibly embedded spaces. Any address provided with the To: header can be either an Address Book nickname or a full email address. Multiple To: addresses can be provided as well as multiple cc: or bcc: addresses. No headers have to be provided with the message. The headers can be provided on the Compose window. However, if this is done, a blank line MUST precede the message body in the message file. Additional RC type errors can be received by this command if the message-file-name is invalid or an error occurred reading in the message file. Each of these errors have a severity level of 5 with one of the following messages placed in the AEMAIL.LASTERROR variable: 105: Error Opening Passed Message 106: Error retrieving passed message If you would like to use the File Requester to obtain the file name before passing it to this command, you can use the GETFILENAME command to obtain the full path name of the message. No validation is made on the To: address in the message. If it is invalid, either the user will receive an error when the message is sent or a message will be received indicating "Returned mail: User unknown". RESULT: 0: The user cancelled the operation. No message was composed. 1: Message composed and placed in PENDING folder. 2: Message composed and placed in QUEUED folder. 3: Message composed and sent. CURRENT IS SELECTED Syntax: CURRENT IS SELECTED This command makes the currently selected message the current message. The currently selected message is the message that is highlighted in the message list or the message that is currently being displayed. The message may or may not have a selection asterick. RESULT: 0 There was no selected message. 1 Current message is now the selected message. DATE Syntax: DATE DATE MDY DATE DMY DATE YMD This command returns the Date: header of the current message header without the "Date:". Without an operand, this command returns the date as it was received in the Date: header of the message. With the operand "MDY" it returns the date as mm/dd/yy. The operand "DMY" returns the date as dd/mm/yy and "YMD" returns yy/mm/dd. All of the fields are two digits which means that yy will be the last 2 digits of the year. The alternate formats are provided so that the date field can be stored in a data base such as one created with "Final Data". RESULT: -1 No current message NULL or blanks No Date: header Date: field EXTRACT Syntax: EXTRACT REALNAME name-string EXTRACT USERID name-string This command extracts either the REALNAME or the USERID (email address or address book nickname) from a name string that is usually the result of the FIRST TONAME, FIRST CCNAME, FIRST BCCNAME or NEXT NAME commands (see below). Because of the various formats of a name string; ie, email-address (Full Name) Full Name <email-address> email-address addressbook-nickname it is easier to use this command rather then to use standard ARexx commands to parse the name string. If you use the ADDRESS_BOOK GET nickname TYPE command you can determine if a userid that is returned is a nickname or email address. The name-string variable should be quoted since it will contain blanks and other characters ARexx may not like including double quote marks. As an example: OPTION RESULTS FIRST TONAME name=RESULT if name = "" THEN EXIT EXTRACT USERID '"'name'"' emailaddr=RESULT ADDRESS_BOOK GET '"'emailaddr'"' TYPE if RESULT = 0 THEN OKAY1 emailaddr" is an individual nickname." ELSE if RESULT = 1 THEN OKAY1 emailaddr" is a group nickname." RESULT: NULL or blank No real name if REAL-NAME operand used. Either the real name or userid string. FIRST This command is used to select the first message in the current folder or to select the first name string from the list of To: or cc: recipients. *** Syntax: FIRST FIRST NEW FIRST SELECTED FIRST DELETED Without an Operand this command selects the first message in the current selected folder as the current message. With the NEW operand, this command selects the first un-read (new) message in the current selected folder as the current message. If a message is unread but deleted, it will NOT be considered an un-read message. With the SELECTED operand, this command selects the first selected (message marked with an asterick) message in the current selected folder as the current message. With the DELETED operand, this command selects the first message marked as deleted in the current selected folder as the current message. NOTE: The order of the messages in the folder is the un-sorted order. This generally means that the first message is the oldest message in the folder. RESULT: 0 No messages of the particular type in the folder 1 First message is now the current message. *** Syntax: FIRST TONAME FIRST CCNAME FIRST BCCNAME This command returns the first name from the appropriate header field (To:, cc:, or bcc:) in the current message. The name can be in one of the following formats: email-address (Full Name) Full Name <email-address> email-address addressbook-nickname Names in the header recipient lists are separated by commas; however, a comma may be embedded within a real name if the real name is surrounded by quotes. If you wish to extract either the Full Name, email-address, or the addressbook-nickname from the RESULT you can set the RESULT to a variable and then use the EXTRACT command with that variable as the argument. RESULT: -1 There is no current message NULL or blank There are no names in this field. The first name in the appropriate header. FLAGS Syntax: FLAGS This command returns the flags for the current message. The flags are returned in the RESULT field as indicated below. A message can have multiple flags which means that a value will be returned with the two or more values for the flags added together. As an example, a message that is unread and new with attachments will return a value of 11. You will need to use the ARexx operator for logical AND to isolate the flag you want. Here is a piece of ARexx code to isolate a message that is unread: OPTION RESULTS FLAGS IF RESULT = -1 THEN OKAY1 "There is no current message" ELSE DO IF RESULT & 2 THEN OKAY1 "This message is unread" ELSE OKAY1 "This message has been read" END Note the distinction between flag values 1 (for New) and 2 (for Unread). Generally, when a message is first read into the system both flags are set. If the message is read, both flags are turned off. However, if the message should be deleted without being read, the Unread flag will be turned off but the New flag will remain on. If that message then becomes un-deleted and the New flag is still on, the Unread flag will be turned back on. RESULT: -1 No current message 0 There is a current message but no flags are set 1 Message is New and unread (can be deleted) 2 Message is unread but not deleted 4 Message is a reply 8 Message has attachments 16 Message has been forwarded 32 Message is deleted 64 Message is selected FOLDER There are a number of variations of the FOLDER command. They are listed below: *** Syntax: FOLDER The FOLDER command with no operands is used to return the current selected folder name. RESULT: 0 No folder currently selected The folder Name (i.e., "INBOX", "QUEUED", etc.) *** Syntax: FOLDER LIST_FOLDERS [pad] This command will list all of the folders in your system. Normally each folder is separated by a space. However, this can be changed by specifying a pad string at the end of the command. You can use the LF keyword to specify a line feed or use some other character sequence for the pad string. As an example: ", " will insert a comma followed by a space between each folder name in the list. Notice that the keyword here is LIST_FOLDERS with an underline between LIST and FOLDERS. If the keyword was simply LIST it might be mis-interpreted as a folder named LIST. RESULT: The list of folders separated by the pad character. *** Syntax: FOLDER folder-name This command selects the the folder indicated by folder-name. RESULT: -1: folder-name is invalid. Could be the result of a misspelling of one of the operands used with the FOLDER commands so that the operand is mis-interpreted as a folder-name. 0: The folder folder-name could not be selected. 1: The folder folder-name was selected. *** Syntax: FOLDER DESCRIPTION FOLDER folder-name DESCRIPTION FOLDER folder-name SELECT DESCRIPTION This command returns the description of either the selected folder or, if present, the folder indicated by folder name. If the folder name is present, it will not become the new selected unless the SELECT keyword immediately follows it. This allows you to obtain the description of a folder without selecting it. NOTE: If the folder-name is left off the command and any of the parameters is misspelled, it could result in the misspelled parameter being mis-interpreted as a folder-name. RESULT: -1: folder-name is invalid. Could be the result of a misspelling of one of the operands used with the following FOLDER commands so that the operand is mis-interpreted as a folder-name. The description of either the folder specified with folder-name or the selected folder. *** Syntax: FOLDER NUMBER_MESSAGES FOLDER folder-name NUMBER_MESSAGES FOLDER folder-name SELECT NUMBER_MESSAGES This command returns the number of messages contained in either the selected folder or, if present, the folder indicated by folder name. If the folder name is present, it will not become the new selected folder unless the SELECT keyword immediately follows it. This allows you to obtain the number of messages from a folder without selecting it. Please note the spelling of the operand NUMBER_MESSAGES with the underline between NUMBER and MESSAGES. This makes the operand string longer than a folder-name so that it does not interfer with any existing folder-name. NOTE: If the folder-name is left off the command and any of the parameters is misspelled, it could result in the misspelled parameter being mis-interpreted as a folder-name. RESULT: -1: folder-name is invalid. Could be the result of a misspelling of one of the operands used with the following FOLDER commands so that the operand is mis-interpreted as a folder-name. n: The total number of messages in the folder including ones that are unread or deleted. *** Syntax: FOLDER NEW_MESSAGES FOLDER folder-name NEW_MESSAGES FOLDER folder-name SELECT NEW_MESSAGES This command returns the number of new (unread) messages contained in either the selected folder or, if present, the folder indicated by folder name. If the folder name is present, it will not become the new selected folder unless the SELECT keyword immediately follows it. This allows you to obtain the number of new messages from a folder without selecting it. If a message is unread but deleted, it will not be included in the count of new messages. Please note the spelling of the operand NEW_MESSAGES with the underline between NEW and MESSAGES. This makes the operand string longer than a folder-name so that it does not interfer with any existing folder-name. NOTE: If the folder-name is left off the command and any of the parameters is misspelled, it could result in the misspelled parameter being mis-interpreted as a folder-name. RESULT: -1: folder-name is invalid. Could be the result of a misspelling of one of the operands used with the following FOLDER commands so that the operand is mis-interpreted as a folder-name. n: The number of new or unread messages in the folder. *** Syntax: FOLDER DELETED_MESSAGES FOLDER folder-name DELETED_MESSAGES FOLDER folder-name SELECT DELETED_MESSAGES This command returns the number of deleted messages contained in either the selected folder or, if present, the folder indicated by folder name. If the folder name is present, it will not become the new selected folder unless the SELECT keyword immediately follows it. This allows you to obtain the number of deleted messages from a folder without selecting it. Please note the spelling of the operand DELETED_MESSAGES with the underline between DELETED and MESSAGES. This makes the operand string longer than a folder-name so that it does not interfer with any existing folder-name. NOTE: If the folder-name is left off the command and any of the parameters is misspelled, it could result in the misspelled parameter being mis-interpreted as a folder-name. RESULT: -1: folder-name is invalid. Could be the result of a misspelling of one of the operands used with the following FOLDER commands so that the operand is mis-interpreted as a folder-name. n: The number of deleted messages in the folder. *** FROM Syntax: FROM This command returns the From: header of the current message without the "From: ". It has no operands. RESULT: -1 No current message NULL or blanks No From: header From: header GETCLIP Syntax: GETCLIP GETCLIP n GETCLIP UNIT n This command will return the current contents of the clipboard in the result variable. If "UNIT n" or "n" is not specified, it will be from the current active clipboard. If "UNIT n" or "n" (without UNIT) is specified it will be from the clipboard unit specified by n. If the clipboard unit is specified, the current active clipboard will be changed to that unit UNLESS the clipboard unit was non-existant. RESULT: NULL or blank This clipboard unit is empty or non-existant. Data from the clipboard unit. *** Syntax: GETCLIP UNIT This command will return the current active clipboard unit number. Notice that is similar to the previous command WITHOUT the clipboard unit number (n). RESULT: n This current active clipboard unit number. GETFILENAME Syntax: GETFILENAME GETFILENAME title GETFILENAME title defaultpath This command brings up the AEMail file requester so you can solicit file names that can be used with commands that require file names. If no operands are provided with this command, the file requester will have "ARexx File Request" as the default title in the requester and a default path of PROGDIR: (the directory from which AEMail was called). The second form of this command allows you to provide your own title in the file requester which may be more descriptive of what kind of file you want. The third form gives the user the ability to provide both a title and a default file path and (if wanted) filename. This is particularly useful if you want to reference a different directory than your program directory. A default filename can be part of this path. NOTE: If you supply a default path without a filename (directory only) you must end the string with ":" or "/" to indicate that it is a directory and not a filename path. Be very careful in using this command since this is one that will require "creative" quoting to insure that you have no more than two operand strings. As an example you should use something like this: GETFILENAME '"The Title String"' '"A file name path"' This will send "The Title String" and "A file name path" to AEMail which will recognize these strings as two quoted operands. RESULT: NULL or blank if the no filename was entered or the requester was cancelled. The full path and filename of the file that was selected. GETLISTITEM Syntax: GETLISTITEM list GETLISTITEM list title This command brings up the AEMail list view requester so the user can solicit a member of the list. The operand list is a list of items, each member of the list being separated by a line feed. Many of the AEMail commands can supply such a list. As an example, "ADDRESS_BOOK LIST GROUP DESCRIPTION LF" will supply a list of group Address Book entries and their descriptions separated by line feeds. Another example is "LIST_FOLDERS LF" which will provide a list of all the folders in the system. The list should be a quoted variable such as: ADDRESS_BOOK LIST GROUP DESCRIPTION LF grplist = RESULT GETLISTITEM "'"grplist"'" This will insure that the entire list is treated as a single variable. The second operand is the title that you want for the list view. If this operand is not provided, the list view requester will have "ARexx Select List Item" as the default title. The title should also be quoted. When the list view is displayed and an item selected from the list it will appear in a string gadget below the listview. You can modify the information in this string gadget if you wish. An [OK] and [CANCEL] gadget will also be displayed. If you click on [OK] or press RETURN, the information in the string gadget will be returned in the RESULT variable. RESULT: NULL or blank if the string gadget is blank or the requester was cancelled. The string that was entered in the string gadget at the bottom of the listview. GETNUMBER Syntax: GETNUMBER GETNUMBER title GETNUMBER title default GETNUMBER title default min GETNUMBER title default min max This command brings up the AEMail numeric requester so you can solicit a numeric value. If no operands are provided with this command, the numeric requester will have "ARexx Enter Number" as the default title in the requester and a default value of 0. The second form of this command allows you to provide your own title in the numeric requester which may be more descriptive of what purpose you want the number for. The third form gives the user the ability to provide both a title and a default numeric value. The fourth form gives you the ability to provide a minimum value that can be entered, and the fifth for allows both a minimum or maximum value. f a value outside this range is entered, the screen will flash. Also, the minimum and maximum limits are given in a text string below the numeric entry gadget. Be very careful in using this command since this is one that will require "creative" quoting for the title to insure that strings between embedded spaces are not interpreted as part of the numeric values. As an example you should use something like this: GETNUMBER '"Enter a number between 3 & 7"' 5 3 7 This will place "Enter a number between 3 & 7" in the title bar of the requester, use 5 as the default value in the numeric entry gadget, and set the minimum and maximum possibilities to 3 and 7 respectively. This will also recognize the full title string as a proper quoted operand. The numeric entry gadget is followed by a [+] (increment) and a [-] (decrement) gadget. Clicking on one or the other of these gadgets will increment or decrement the value in the numeric entry gadget. This value can not decrement below the minimum value or 0 (if no minimum is given) or increment above the maximum value. The numeric entry gadget is in "replace" mode so that entering a number will replace what was previously there. Hitting [OK] or pressing the RETURN key will terminate the requester with the numeric value entered returned in the RESULT variable. RESULT: NULL or blank if the the requester was cancelled. n The numeric value entered in the requester. GETSIZE Syntax: GETSIZE MESSAGE GETSIZE TEXT This command will get the size of the Current Message. If the operand "MESSAGE" is given, it will be the size of the complete message. If the operand "TEXT" is given, it will be only the size of the text portion of the message (Message size less the header size and any attachment size). RESULT: 0 No Current Message The size of the Current Message or just the text size. GETSTRING Syntax: GETSTRING GETSTRING title GETSTRING title defaultstring This command brings up the AEMail string requester so you can solicit a string from the user. If no operands are provided with this command, the string requester will have "ARexx Enter String" as the default title in the requester with no default string. The second form of this command allows you to provide your own title in the string requester which may be more descriptive of what purpose you want the string for. The third form gives the user the ability to provide both a title and a default string that will appear in the requester when it is first brought up. Be very careful in using this command since this is one that will require "creative" quoting to insure that you have no more than two operand strings. As an example you should use something like this: GETSTRING '"Enter a Folder Name"' '"INBOX"' This will send "Enter a Folder Name" and "INBOX" to AEMail which will recognize these strings as two separate quoted operands. Since INBOX is one word, it does not have to have the special quoting on it but can be simply 'INBOX'. RESULT: NULL or blank if the no string was entered or the requester was cancelled. The string that was entered in the requester. GETVAR Syntax: GETVAR When you are displaying a message and you double click on a message line, the Clipboard Window appears. If you hit one of the function keys to call an ARexx script, the line currently being displayed in the clipboard string will be transferred to a special variable. In your ARexx script you can use GETVAR to extract that string. If the string was an email or web address, your script can use the variable thus obtained to send a message to the email address or to call your web browser to go to the web address. RESULT: The string that was in the clipboard line. LAST Syntax: LAST LAST NEW LAST SELECTED LAST DELETED Without an Operand this command selects the last message in the current selected folder as the current message. With the NEW operand, this command selects the last un-read (new) message in the current selected folder as the current message. If a message is unread but deleted, it will NOT be considered an un-read message. With the SELECTED operand, this command selects the last selected (message marked with an asterick) message in the current selected folder as the current message. With the DELETED operand, this command selects the last message marked as deleted in the current selected folder as the current message. NOTE: The order of the messages in the folder is the un-sorted order. This generally means that the last message is the newest message in the folder. RESULT: 0 No messages of the particular type in the folder 1 Last message is now the current message. MESSAGE This command is used to set various flags on the Current Message. After the execution of this command, the message list, if it is currently being displayed, will be re-displayed with the changed status. The forms of this command are as follows: Syntax: MESSAGE SELECT This command marks the Current Message as selected. RESULT: -1 There is no Current Message. 0 The Current Message is already marked as selected. 1 The Current Message is now marked as selected. *** Syntax: MESSAGE UNSELECT This command marks the Current Message as un-selected. RESULT: -1 There is no Current Message. 0 The Current Message is not marked as selected. 1 The Current Message is now marked as un-selected. *** Syntax: MESSAGE DELETE This command marks the Current Message as deleted. RESULT: -1 There is no Current Message. 0 The Current Message is already marked as deleted. 1 The Current Message is now marked as deleted. *** Syntax: MESSAGE UNDELETE This command marks the Current Message as not deleted. RESULT: -1 There is no Current Message. 0 The Current Message is not currently marked as deleted. 1 The Current Message is now no longer marked as deleted. *** Syntax: MESSAGE READ This command marks the Current Message as being read. RESULT: -1 There is no Current Message. 0 The Current Message is already marked as being read. 1 The Current Message is now marked as being read. *** Syntax: MESSAGE MAKE NEW This command marks the Current Message as unread or new. NOTE: If the message was marked as deleted, only the "new" flag is set; otherwise, both the "new" and "unread" flags are set. RESULT: -1 There is no Current Message. 0 The Current Message is already marked as unread (new). 1 The Current Message is now marked as unread. *** Syntax: MESSAGE SELECT ALL All messages in the current selected folder are marked as selected. This command does not change the Current Message status. RESULT: 0 There are no messages in the selected folder. 1 All of the messages in the selected folder are marked as selected. *** Syntax: MESSAGE SELECT NONE MESSAGE UNSELECT ALL This command can be expressed in either form above. All messages in the current selected folder are marked as un-selected. This command does not change the Current Message status. RESULT: 0 There are no messages in the selected folder. 1 All of the messages in the selected folder are now marked as un-selected. NEXT This command is used to select the next message in the current folder or to select the next name string from the list of To: or cc: recipients. *** Syntax: NEXT NEXT NEW NEXT SELECTED NEXT DELETED Without an operand this command selects the next message, regardless of it's status, in the current selected folder as the current message. With the NEW operand, this command selects the next un-read (new) message in the current selected folder as the current message. If a message is unread but deleted, it will NOT be considered an un-read message. With the SELECTED operand, this command selects the next selected (message marked with an asterick) message in the current selected folder as the current message. With the DELETED operand, this command selects the next message marked as deleted in the current selected folder as the current message. NOTE: The order of the messages in the folder is the un-sorted order. This generally means that the order of the messages in the folder is that older messages are before newer messages. RESULT: 0 No more messages of the particular type are in the folder. At the end of the message list. 1 The next message is now the current message. *** Syntax: NEXT NAME This command returns the next name from the header field that was referenced by the last FIRST command. A FIRST TONAME, FIRST CCNAME, or FIRST BCCNAME command must have been issued prior to issuing the first NEXT NAME command. Each NEXT NAME command that is issued retrieves the next name in that header field. Once the end of the name list is reached, another FIRST command must be issued before another NEXT NAME command is issued. The name can be in one of the following formats: email-address (Full Name) Full Name <email-address> email-address addressbook-nickname Names in the header recipient lists are separated by commas; however, a comma may be embedded within a real name if the real name is surrounded by quotes. If you wish to extract either the Full Name, email-address, or the addressbook-nickname from the RESULT you can set the RESULT to a variable and then use the EXTRACT command with that variable as the arguement. RESULT: -2 The name string has not been started with the FIRST command. NULL or blank You are at the end of the list. There are no more names in the current header field. The next name in the appropriate header. OKAY1 Syntax: OKAY1 text This commands presents the AEMail notification requester containing the supplied text. If there are any ARexx specific command operators within the text stream, the stream should be surrounded in quotes. The notification requester has one button marked "Continue". Clicking on this button will terminate the requester and the OKAY1 command. Warning: Be careful of the size of the text string that you pass to this command. If the string is too long without intervening line feeds, the "Continue" button could be positioned off the screen and you will have no way to terminate the requester. This can be particularly true of returned strings that are being displayed. It is best to use the ARexx LEFT() function to insure you have a short enough string. RESULT: 1 Always returned OKAY2 Syntax: OKAY1 responses text This commands presents the AEMail notification requester containing the supplied text. If there are any ARexx specific command operators within the text stream, the stream should be surrounded in quotes. "responses" provides a list of possible responses to the requester. Any number of responses can be provided. Each response must be separated by the vertical bar ("|"). The entire response string must be surrounded by quote marks. The notification requester has as many buttons as they are responses. The wording in these buttons is controlled by the response string. Clicking on any of these buttons will terminate the requester and the OKAY2 command. RESULT: 0 The last response in the response string was selected. 1 The first response was selected. n The second through nth (last - 1) response was selected. PREVIOUS Syntax: PREVIOUS PREVIOUS NEW PREVIOUS SELECTED PREVIOUS DELETED Without an operand this command selects the previous message, regardless of it's status, in the current selected folder as the current message. With the NEW operand, this command selects the previous un-read (new) message in the current selected folder as the current message. If a message is unread but deleted, it will NOT be considered an un-read message. With the SELECTED operand, this command selects the previous selected (message marked with an asterick) message in the current selected folder as the current message. With the DELETED operand, this command selects the previous message marked as deleted in the current selected folder as the current message. NOTE: The order of the messages in the folder is the un-sorted order. This generally means that the order of the messages in the folder is that older messages are before newer messages. RESULT: 0 No more messages of the particular type are in the folder. At the beginning of the message list. 1 The next previous is now the current message. QUEUE Syntax: QUEUE "message-file-name" [MAILTO userid] The message file indicated by "message-file-name" will be read into the system and will be placed in the QUEUED folder. This message must have correctly formatted headers. A blank line must separate the headers from the body of the message. The "message-file-name" should be the full path name of the message file and it should be quoted since the path will contain characters that ARexx will attempt to interpret as operators. It may also contain embedded spaces. If it does contain embedded spaces, double quote pairs must be used, ie. '"filename string"' or '"'variable'"'. Any address provided with the To: header can be either an Address Book nickname or a full email address. Multiple To: addresses can be provided as well as multiple cc: or bcc: addresses. Instead of a To: address provided in the message the optional MAILTO keyword can be used to provide a userid which can be an Address Book nickname or an email address. The MAILTO address will be added to any addresses provide with a To: header. If the From: or Reply-To: addresses are not given, these addresses will be taken from the default From: and Reply-To addresses. Any Date: header is ignored since the Date: header will be constructed when the message is sent. Any other non-standard headers can be supplied in the message file and they will be included with the message. Only the To: header has to be provided unless the MAILTO parameter is given. If the MAILTO parameter is used, no headers have to be provided with the message. However, if this is done, a blank line MUST be the first line in the message file. Additional RC type errors can be received by this command if the message-file-name is invalid or an error occurred reading in the message file. Each of these errors have a severity level of 5 with one of the following messages placed in the AEMAIL.LASTERROR variable: 105: Error Opening Passed Message 106: Error retrieving passed message No validation is made on the To: address in the message. If it is invalid, either the user will receive an error when the message is sent or a message will be received indicating "Returned mail: User unknown". RESULT: 1: Message was placed in the QUEUED folder. QUIT Syntax: QUIT This command will terminate AEMail. It operates silently so no messages will appear. After issuing this command, you can not issue any more commands to AEMail since AEMail and the AEMail ARexx Port will no longer be there to receive amy commands. RESULT: None REPLYTO Syntax: REPLYTO This command returns the Reply-To: header of the current message without the "Reply-To: ". It has no operands. RESULT: -1 No current message NULL or blanks No Reply-To: header Reply-To: header SAVE This command can save the current message or selected messages or the text portion of a message to a file. The current message or current message text can also be directly returned in the RESULT variable. The Current Message text can also be saved to the clipboard. The various forms of this command are given below: Syntax: SAVE MESSAGE This command will return the Current Message in the RESULT variable. This will be the complete message including all headers, message body, and all attachments. WARNING: This will return only the first 4092 characters of the current message. Line Feed characters will be included at the end of each line in the message. You can use the GETSIZE MESSAGE command to obtain the size of the message to see if it will fit. RESULT: NULL or blank There is no Current Message The message (up to 4092 characters) *** Syntax: SAVE MESSAGE [TO] filename This command will save the Current Message to the file whose complete path and file name is filename. This should be a quoted variable. You can solicit a filename by using the GETFILENAME command before issuing this command. The keyword TO is optional. The message saved is the complete message including all headers, message body, and all attachments. Except for available disk space, there is no limit on the size of the message. Line Feed characters will be included at the end of each line in the message. RESULT: 0 There is no current message 1 The current message has been saved. *** Syntax: SAVE SELECTED MESSAGES [TO] filename This command will save all of the selected messages in the current selected folder to the file whose complete path and file name is filename. This should be a quoted variable. You can solicit a filename by using the GETFILENAME command before issuing this command. All of the messages will be saved in the single file specified as a block of messages. The keyword TO is optional. The messages saved include the complete message including all headers, message body, and all attachments. Except for available disk space, there is no limit on the size of the message. Line Feed characters will be included at the end of each line in the message. RESULT: 0 There is no messages selected 1 The current message has been saved. *** Syntax: SAVE TEXT SAVE TEXT NOLF This command will return the text body of the Current Message in the RESULT variable. This will be only the body text without headers or attachments. Normally the text is returned with a line feed separating each line. If you use the "NOLF" operand, this line feed will be left off. This means that the body lines will be one continuous string of data. This can be very helpful if you have a short message generated by a forms command sent by email in a web page. WARNING: This will return only the first 4092 characters of the current message body text. Line Feed characters will be included at the end of each line in the message unless NOLF is specified. You can use the GETSIZE TEXT command to obtain the size of the message body to see if it will fit. RESULT: NULL or blank There is no Current Message The message text (up to 4092 characters) *** Syntax: SAVE TEXT [TO] filename This command will save the text body of the Current Message to the file whose complete path and file name is filename. This should be a quoted variable. You can solicit a filename by using the GETFILENAME command before issuing this command. The keyword TO is optional. The text saved is only the body text without headers or attachments. Except for available disk space, there is no limit on the size of the message text. Line Feed characters will be included at the end of each line in the message. RESULT: 0 There is no current message 1 The current message text has been saved. *** Syntax: SAVE TEXT [TO] CLIPBOARD SAVE TEXT [TO] CLIPBOARD n The first form of this command will save the text body of the Current Message to the clipboard unit that is currently active. The second form will allow you to save the text to the clipboard unit specified by n. You can determine which clipboard is currently active by using the GETCLIP UNIT command. If you use the "n" parameter, the currently active clipboard unit will be changed to n after the command is successfully executed (RESULT of 1). The keyword TO is optional. The text saved is only the body text without headers or attachments. Except for available RAM space, there is no limit on the size of the message text. Line Feed characters will be included at the end of each line in the message. RESULT: 0 There is no current message 1 The current message text has been saved to the clipboard. *** Syntax: SAVE "string of text" [TO] CLIPBOARD SAVE "string of text" [TO] CLIPBOARD n The first form of this command will save the string of text passed as a quoted string to the clipboard unit that is currently active. The second form will allow you to save the string to the clipboard unit specified by n. You can determine which clipboard is currently active by using the GETCLIP UNIT command. If you use the "n" parameter, the currently active clipboard unit will be changed to n after the command is successfully executed (RESULT of 1). The keyword TO is optional. The keyword TO is optional. The string saved must be quoted to allow for embedded spaces and special characters. As an example: SAVE '"This is a string of characters"' TO CLIPBOARD 3 will save the string "This is a string of characters" to clipboard number 3. The string is limited to 119 characters. If a larger string is given it will be truncated at 119 characters. RESULT: 1 The string has been saved to the clipboard. SCREENTOBACK Syntax: SCREENTOBACK AEMAIL SCREENTOBACK WORKBENCH SCREENTOBACK public-screen-name This command brings either the AEMail screen, the Workbench screen or the named public-screen-name to the back of the display. RESULT: 0 The public-screen-name is invalid or no longer open 1 The specified screen has been moved to the back. SCREENTOFRONT Syntax: SCREENTOFRONT AEMAIL SCREENTOFRONT WORKBENCH SCREENTOFRONT public-screen-name This command brings either the AEMail screen, the Workbench screen or the named public-screen-name to the front of the display. RESULT: 0 The public-screen-name is invalid or no longer open 1 The specified screen is now the front most screen. SUBJECT Syntax: SUBJECT This command returns the Subject: header of the current message without "Subject: ". It has no operands. Also, the RE: and (fwd), if present, is stripped from the header string. You can use the FLAGS command to determine if the current message is a reply or forwarded message. RESULT: -1 No current message NULL or blanks No Subject: header Subject: header TO Syntax: TO This command returns the To: header of the current message without the "To: ". It has no operands. RESULT: -1 No current message NULL or blanks No To: header To: header Error Messages -------------- When a command returns an RC value other than 0 the RC code represents a severity code. Severity codes are usually 5 or 20. A string error message will also appear in the AEMAIL.LASTERROR variable. These errors can be interrogated and displayed. The errors that you can expect from AEMail are as follows: "100: Unknown command" "101: Syntax Error" "102: No Operand Required" "103: Missing Operand" "104: Too Many Operands" "105: Error Opening Passed Message" "106: Error retrieving passed message" "110: Out of Memory" Additional errors which will not have a error message number associated with them are: "Unable to open input mail file" "Error reading input mail file" "Unable to open output file" "Error writing to output file"